{
    title:  'Configuring ESP',
    crumbs: [
        { "User's Guide": 'index.html' },
    ],
}
            <h1>Configuring ESP</h1>
            <p>When serving stand-alone <em>esp</em> pages, you do not need any external ESP configuration.
            ESP provides sensible defaults and you can just run <em>esp serve</em> to serve pages. </p>

            <code class="inverted">$ <b>esp serve</b></code>

            <p>However, larger ESP applications are configured via the 
            <em>esp.json</em>, <em>package.json</em> and <em>expansive.json</em>
            files that permits fine-grained control over how the application will run </p>

            <p>The <em>package.json</em> file manages:</p>
            <ul>
                <li>Application name, title and description</li>
                <li>Application version</li>
                <li>Directory locations</li>
                <li>Application execution mode</li>
                <li>Extension package dependencies</li>
            </ul>

            <p>The <em>esp.json</em> file manages:</p>
            <ul>
                <li>Client-side scripts</li>
                <li>Per-mode (debug or release) configuration</li>
                <li>Response Caching</li>
                <li>Request timeouts</li>
                <li>Error handling</li>
                <li>Database name and location</li>
                <li>Default data formats</li>
            </ul>

            <p>The <em>expansive.json</em> will be installed by most skeletons. It manages:</p>
            <ul>
                <li>Expansive layouts and partial pages</li>
                <li>Expansive tooling</li>
                <li>Expansive plugins for processing content</li>
            </ul>

            <p>This document will cover the various <em>esp.json</em> properties and the steps to configure ESP 
            applications. See the <a href="https://embedthis.com/expansive/doc/">Expansive Documentation</a>
            for details about the <em>expansive.json</em>.</p>
            <p>If you are hosting your application in Appweb you will need to specify additional 
            configuration in the <em>appweb.conf</em> configuration file. For details, see
                the <a href="hosting.html">Hosting in Appweb</a>.</p>

            <h2>package.json</h2>
            <p>The <em>package.json</em> file contains your application name, description, version and 
            specifies any required packages that your application depends upon. The format is a JSON literal. 
            For example:</p>
<code class="inverted">{
    "name": "blog",
    "title": "My Blog",
    "description": "My blog with thoughts and tales from my travels in Africa",
    "version": "1.0.0",
    "dependencies": {
        "jquery": "^2.1"
    }
}</code>
            <h3>Name and Description</h3>
            <p>All ESP applications have name, title, description and version properties that uniquely identify 
            the application. The application name is used in C function entry points, so it is important that 
            it only contain valid C identifer characters. The title provides a multi-word title suitable 
            for display to the user. The description is used should you publish your application in a package 
            catalog.</p>

            <h3>Dependencies</h3>
            <p>The <em>dependencies</em> hash lists all the installed packages and the required versions.
            Entries will be added as packages are installed via <em>pak install</em>. For example:</p>
            <code class="inverted">$ pak install jquery</code>
            <p>ESP relies heavily on the <a href="https://embedthis.com/pak/">Pak</a> package manager to install
            and manage extension packages. There are many thousands to choose from the 
            <a href="https://embedthis.com/pak/">Pak</a> and NPM package catalogs.</p>

            <h2>esp.json</h2>
            <p>The <em>esp.json</em> file provides configuration for ESP and how HTTP requests will be served.
            The format is an enhanced JSON literal that supports property names without quotes, multi-line 
            literals and commas on trailing properties. Here is the initial generated contents of the 
            <em>esp.json</em></p>
            <code>{
    esp: {
        app: true
    },
    http: {
        server: {
            listen: [
                "http://127.0.0.1:4000"
            ]
        },
        ssl: {
            certificate: "",
            key: ""
        }
    }
}</code>

            <h2>Creating Configuration Files</h2>
            <p>To create an <em>esp.json</em> and <em>package.json</em>, run the following in an empty directory.</p>
            <code class="inverted"><b>esp init</b></code>

            <p>Alternatively, or if you install an ESP skeleton, then the <em>esp.json</em> and <em>package.json</em> 
            files will be created for you. For example:</p>

            <code class="inverted"><b>pak install esp-html-skeleton</b></code>

            <a id="mode"></a>
            <h2>Configuration Mode</h2>
            <p>ESP provides a convenient way to select a set of properties that correspond to a desired execution
            mode such as: <em>debug</em>, <em>test</em> or <em>release</em> modes. In each mode, different 
            configuration may be defined.</p>

            <p>The selected mode is specified by the <em>mode</em> property in the <em>package.json</em> file.
            This then selects a collection of properties of that same name that will be copied to the 
            top-level before the application runs. By modifying the <em>mode</em> setting, an entirely 
            different execution configuration may be selected. ESP makes this easy via the command:</p>

            <code class="inverted">$ esp mode debug</code>

            <p>This will set the <em>pak.mode</em> property to <em>debug</em> in the <em>package.json</em> file
            and select the <em>debug</em> collection of properties in the <em>esp.json</em> file.
            The <em>mode</em> property is centralized in the <em>package.json</em> file because the 
            <a href="https://embedthis.com/pak/">Pak</a> and <a href="https://embedthis.com/expansive/">Expansive</a> 
            utilities follow a similar scheme and having one single <em>mode</em> property is
            desirable over each utility replicating the mode definition.</p>

            <h2>Package.json Properties</h2>
            <table title="top-level collections" class="ui table segment">
                <thead>
                    <tr><th>Name</th><th>Description</th></tr>
                </thead>
                <tbody>
                    <tr>
                        <td>description</td>
                        <td>Short sentence description of the application.</td>
                    </tr>
                    <tr>
                        <td>dependencies</td>
                        <td>Extension packages used by the ESP application. The key is the pak name and the value is a 
                        <a href="http://semver.org">SemVer</a> version expression. 
                        See <a href="https://embedthis.com/pak/doc/index.html">Pak</a> Documentation for details.</td>
                    </tr>
                    <tr>
                        <td><a href="#directories">directories</a></td>
                        <td>Directory locations</td>
                    </tr>
                    <tr>
                        <td>include</td>
                        <td>List of external files to include.</td>
                    </tr>
                    <tr>
                        <td>name</td>
                        <td>One word application name. This value is used to name the application and will be used
                            in controller and application function entry point names.</td>
                    </tr>
                    <tr>
                        <td>pak.mode</td>
                        <td>Configuration mode for the application that selects a property collection of the 
                        same name from the <em>modes</em> collection in the <em>package.json</em> and 
                        <em>esp.json</em> files. Those properties are copied up to the top level.</td>
                    </tr>
                    <tr>
                        <td>title</td>
                        <td>Multi-word application name to display.</td>
                    </tr>
                    <tr>
                        <td>version</td>
                        <td>Application version conforming to <a href="http://semver.org">SemVer</a>.</td>
                    </tr>
                </tbody>
            </table>

            <a name="dependencies"></a>
            <h3>Dependency Expressions</h3>
            <p>Dependent extension packages may be specified in the <em>dependencies</em> property. This is an object 
            collection of paks with version expressions. When Pak installs a package, an entry for the new pak
            will be added to the dependency collection. For example:</p>

            <code class="inverted">"dependencies": {
    "jquery": "1.11.0",
    "bootstrap": "3.0.0",
}</code>

            <h4>Dependency Versions</h4>
            <p>ESP versions comply with the <a href="http://semver.org">SemVer</a> version specification.
            Briefly, this means versions are expressed :</p>
            <code class="inverted">MAJOR.MINOR.PATCH-PRERELEASE</code> 
            <p>Dependency versions may also include expressions that describe a range of acceptable pak versions.</p>
            <ul>
                <li>version &mdash; (allows pre-releases)</li>
                <li>^ version &mdash; (same as &gt;=1.2.3 &lt;2.0.0, does not allow pre-releases)</li>
                <li>~ version &mdash; (same as &gt;=1.2.3 &lt;2.0.0, allows pre-releases)</li>
                <li>1.2.X &mdash; (any version starting with 1.2 (allows pre-releases)</li>
                <li>[&gt;, &gt;=, &lt;, &lt;=, ==, !=] version</li>
                <li>expression || expression ... (either expression qualifies)</li>
                <li>expression &amp;&amp; expression ... (both expressions must qualify)</li>
                <li>expression expression ... (same as &amp;&amp;) </li>
            </ul>
            <p>For example:</p>

            <code class="inverted">"dependencies": {
    "bootstrap": "~3",     /* Versions 3.0.0 or later including pre-releases */
    "jquery": "^1.9.1",    /* Version 1.9.1 and not pre-releases */
    "less": "1.3.x",       /* Version 1.3.x and pre-releases /
}</code>

            <a name="directories"></a>
            <h3>Directory Configuration &mdash; directories.*</h3>
            <table title="directory" class="ui table segment">
                <thead>
                    <tr><th>Name</th><th>Description</th></tr>
                </thead>
                <tbody>
                    <tr>
                        <td>cache</td>
                        <td>Directory for caching compiled items. Defaults to <em>cache</em>.</td>
                    </tr>

                    <tr>
                        <td>controllers</td>
                        <td>Directory for server-side MVC controllers. Defaults to "<em>controllers</em>".</td>
                    </tr>
                    <tr>
                        <td>db</td>
                        <td>Directory for server-side database files. Defaults to "<em>db</em>".</td>
                    </tr>

                    <tr>
                        <td>documents</td>
                        <td>Directory containing client visible document content. All files under this
                            directory are visible to the client. Defaults to <em>documents</em>.</td>
                    </tr>
                    <tr>
                        <td>home</td>
                        <td>Home directory for the application. Defaults to "<em>.</em>".</td>
                    </tr>
                    <tr>
                        <td>layouts</td>
                        <td>Directory for <a href="https://embedthis.com/expansive/">Expansive</a> layout pages. 
                        Defaults to "<em>layouts</em>".</td>
                    </tr>
                    <tr>
                        <td>lib</td>
                        <td>Directory for public extension pack scripts and resources. Defaults to "<em>client/lib</em>".</td>
                    </tr>
                    <tr>
                        <td>paks</td>
                        <td>Directory to contain installed packages. Defaults to "<em>./paks</em>".</td>
                    </tr>
                    <tr>
                        <td>partials</td>
                        <td>Directory for <a href="https://embedthis.com/expansive/">Expansive</a> partial pages. 
                        Defaults to "<em>partials</em>".</td>
                    </tr>
                    <tr>
                        <td>pakcache</td>
                        <td>Location of the per-user cache of packages. Defaults to "<em>~/.paks</em>".</td>
                    </tr>
                    <tr>
                        <td>source</td>
                        <td>Source of input documents for <a href="https://embedthis.com/expansive/">Expansive</a>
                        to render. Defaults to "source". </td>
                    </tr>
                    <tr>
                        <td>src</td>
                        <td>Directory for application C/C++ code. Defaults to "<em>src</em>".</td>
                    </tr>
                    <tr>
                        <td>upload</td>
                        <td>Directory for uploaded files. Defaults to "<em>/tmp</em>".</td>
                    </tr>
                </tbody>
            </table>

            <h2>Esp.json Properties</h2>
            <a name="top"></a>
            <table title="top" class="ui table segment">
                <thead>
                    <tr><th>Name</th><th>Description</th></tr>
                </thead>
                <tbody>
                    <tr>
                        <td><a href="#esp">esp</a></td>
                        <td>Collection of ESP configuration.</td>
                    </tr>
                    <tr>
                        <td><a href="#http">http</a></td>
                        <td>Collection of HTTP configuration.</td>
                    </tr>

                    <tr>
                        <td>modes</td>
                        <td>Collection of mode specific configuration. Typically there will be collections for
                        <em>debug</em> or <em>release</em> but can be any identifier word. </td>
                    </tr>
                </tbody>
            </table>

            <a name="client"></a>
            <h3>Client Configuration &mdash; http.client.*</h3>
            <table title="client" class="ui table segment">
                <thead>
                    <tr><th>Name</th><th>Description</th></tr>
                </thead>
                <tbody>
                    <tr>
                        <td>mappings</td>
                        <td><p>Set of property keys that map server-side properties to client-side properties to send to the client. 
                        Mappings select a subset of properties so the entire JSON configuration is not sent to the client.
                        For example: </p>
<code class="inverted">
mappings: {
    auth: 'http.auth',
    timeouts: {
        session: 'http.timeouts.session',
    }
}</code>
                            <p>This computes a JSON string with properties "auth" and "timeouts" to send to the client.</p>
                            </td>
                        </tr>
                    <tr>
<!--  MOB - move -->
                        <td>render</td>
                        <td><p>Ordered set of scripts to send to the client when parsing the ESP <em>scripts()</em> 
                            API. This may include the "*" wildcard to match any file or "**" to match any file in 
                            any directory. For example:</p>
                  <code class="inverted">render: {                    
    js: [
        'lib/angular/angular.js',
        'lib/angular/angular-animate.js',
        'lib/angular/angular-route.js',
        'main.js',
        '*/**.js*'
    ]
}</code></td>
                    </tr>
                </tbody>
            </table>

            <a name="esp"></a>
            <h3>ESP Collection &mdash; esp.*</h3>
            <table title="esp" class="ui table segment">
                <thead>
                    <tr><th>Name</th><th>Description</th></tr>
                </thead>
                <tbody>
                    <tr>
                        <td>app</td>
                        <td><p>Define whether the directory contains an ESP application or stand-alone ESP pages.
                        For example:<code class="inverted">app: true</code></p>
                        <p>An ESP application follows an MVC design pattern and provides controllers to respond to 
                        client requests and views to render responses. An ESP application differs from stand-alone 
                        ESP pages in that it pre-configures ESP for the MVC pattern. This includes defining the 
                        standard directories: <em>cache</em>, 
                        <em>controllers</em>, <em>contents</em>, <em>db</em>, <em>layouts</em>, 
                        <em>migrations</em>, <em>paks</em> and <em>partials</em>.</p>
                        </td>
                    </tr>
                    <tr>
                        <td>apps</td>
                        <td><p>Define external ESP applications to load. ESP can host multiple applications by defining
                            the URI prefix and ESP configuration file for each application. This directive takes three
                            forms. The first is just a simple string with the path to the configuration file for a single
                            application. The URI prefix is determined by the last path segment before the 
                            <em>esp.json</em> filename.</p>
                            <p>The second form takes an array of esp configuration file names. Both these forms may use
                            wild-cards in the filename. The last form is an array of URI prefix and config file 
                            properties for each application.</p>

                        <p>Examples: <code class="inverted">
apps: 'blog/esp.json',
apps: [ 'apps/*/esp.json', 'test/*/esp.json' ],
apps: [ 
    { 
        prefix: '/blog', 
        config: 'apps/blog/esp.json' 
    }
]
</code></p></td>
                    </tr>
                    <tr>
                        <td>build</td>
                        <td>Collection of compilation and link command lines for various platforms.</td>
                    </tr>
                    <tr>
                        <td>combine</td>
                        <td>Define whether to combine the entire ESP application into a single output source 
                            file and library. This is typically enabled for release mode. Defaults to false.</td>
                    </tr>
                    <tr>
                        <td>compile</td>
                        <td>Enable compiling controllers, modules and views at runtime. Defaults to true.</td>
                    </tr>
                    <tr>
                        <td>optimize</td>
                        <td>Define whether to compile optimized or with debug symbols. Set to "true" for an optimized
                            build and to "false" for building with debug symbols.
                            Defaults to false.</td>
                    </tr>
                    <tr>
                        <td>generate</td>
                        <td>Collection of properties guiding the <em>esp generate</em> commands.</td>
                    </tr>
                    <tr>
                        <td>keep</td>
                        <td>Preserve intermediate source code in the cache directory for debugging. Defaults to false
                            unless the package.json pak.mode is set to "debug".</td>
                    </tr>
                    <tr>
                        <td>preload</td>
                        <td>List of source files to preload when starting the application.
                        For example: <code class="inverted">preload: [ 'auth.c' ]</code></td>
                    </tr>
                    <tr>
                        <td>rules</td>
                        <td>Path to the JSON file containing the compilation rules. Defaults to 
                            <em>esp-compile.json</em> in the ESP installation directory. If you want to modify 
                            this file, take a copy and then set the <em>compile</em> property to point to it.</td>
                    </tr>
                    <tr>
                        <td>update</td>
                        <td>Determine if updating of responding applications and pages is enabled. 
                            Some web frameworks will automatically rebuild or reload applications if the source is modified.</td>
                    </tr>
                </tbody>
            </table>

            <a name="http"></a>
            <h3>Http Configuration &mdash; http.*</h3>
            <p>All properties in the <em>http</em> collection with the exception of the <em>http.server</em> 
            collection apply per-route. This means these properties they may be nested in routes defined under
            <em>http.routes</em>. The <em>http.server</em> collection is ignored if ESP is hosted in a web server
            such as Appweb.</p>
            <table title="http" class="ui table segment">
                <thead>
                    <tr><th>Name</th><th>Description</th></tr>
                </thead>
                <tbody>
                    <tr>
                        <td>aliases</td>
                        <td>Collection of URL to directory mapping aliases. The property key is the leading URI prefix
                            and the value is the directory</td>
                    </tr>
                    <tr>
                        <td>attach</td>
                        <td>
                        <a name="attach"></a>
                        List of listen endpoints on which to attach a virtual host.
                        For example:
<code class="inverted">attach: [
    '*:80',
],</code>
                        <p>If there is no attach property, the virtual host will attach to all listening endpoints.</p>
                        </td>
                    </tr>
                    <tr>
                        <td><a href="#auth">auth</a></td>
                        <td>Collection of authentication configuration.</td>
                    </tr>
                    <tr>
                        <td><a href="#cache">cache</a></td>
                        <td>List of cache directives.</td>
                    </tr>
                    <!--
                    <tr>
                        <td><a href="#condition">condition</a></td>
                        <td><p>Define a pre-condition that must be true for the route to be selected.
                        <p>The Condition directive supports four rule varieties: </p>
                        <ul>
                            <li>missing &mdash; True if the default request filename is missing.</li>
                            <li>directory &mdash; True the if rule argument evaluates to a directory</li>
                            <li>exists &mdash; True if the rule argument evaluates to an existing file</li>
                            <li>match &mdash; True if the regular expression pattern matches the string argument</li>
                        </ul>

                        <p>The rule result can be negated by prefixing with "<em>!</em>".</p>
                        <p>The condition property supports the following forms:</p>
                        <ul>
                            <li>Condition [!] rule details ...</li>
                            <li>Condition [!] missing</li>
                            <li>Condition [!] directory string</li>
                            <li>Condition [!] exists string</li>
                            <li>Condition [!] match string regular-expression-pattern</li>
                        </ul>
                        <p>For example:</p>
                        <pre class="code">
conditions: {
    missing: 'true'
    directory: '${request:filename}
    exists: '! exists ${request:filename}
    match: '${header:User-Agent} (Chrome|Safari) 
</pre>
                        </td>
                    </tr>
                        -->
                    <tr>
                        <td>compress</td>
                        <td><p>Enable serving of compressed content. ESP can serve files compressed with gzip and with an
                            additional <b>.gz</b> extension. ESP adds the appropriate HTTP header so the browser can
                            automatically decompress. Ideal for big files or slow networks.</p>
                            <code class="inverted">compress: true
  or
compress: [ 'html', 'js', 'css' ]
</code>
                            <p>If the Expansive exp-gzip extension is installed, suitable static content will be 
                                automatically gzipped.</p>
                            </td>
                    </tr>
                    <tr>
                        <td>database</td>
                        <td>Database to create and open for the application. Of the form:
                            <em>provider://name.ext</em> where provider is set to either "mdb" for the
                            embedded memory database or "sdb" for SQLite. The extensions are "mdb" or "sdb"
                            by convention. Set to "<em>default</em>" for a database named after the application with
                            the default database provider.</td>
                    </tr>
                    <tr>
                        <td>deleteUploads</td>
                        <td>Define if uploaded files should be automatically deleted after the request or if they should
                            accumulate in the upload directory.</td>
                    </tr>
                    <tr>
                        <td>domain</td>
                        <td>Matching domain for virtual hosting. 
                        For example: <code class="inverted">domain: '*embedthis',</code></td>
                    </tr>
                    <tr>
                        <td>errors</td>
                        <td>Collection of error pages to serve for various HTTP status codes.
                        For example: <code class="inverted">errors: {
    '404': '/notFound.html,
},</code></td>
                    </tr>
<!--
                    <tr>
                        <td>formats</td>
                        <td>Collection default data formats for various data types. The <em>response</em> property specifies
                        the default client-server interchange format. It can be set to "html" or "json".
                        For dates, the property specifies an 
                        <a href="https://docs.angularjs.org/api/ng/filter/date">Angular</a> style date format. For
                        floats, it specifies the default number of decimal places.
                        For example:
                        <code class="inverted">formats': {
    response: 'json',
    date: 'yyyy-MM-dd',
    float: 2,
},</code></td>
                    </tr>
-->
                    <tr>
                        <td>headers</td>
                        <td>Collection response header directives. This includes sub-collections for headers to 
                            "<em>add</em>", "<em>remove</em>"" and "<em>set</em>". The "<em>remove</em>"" collection is a list, whereas 
                            "<em>add</em>" and "<em>set</em>" are collections.
                            For example:
<code class="inverted">headers: {
    add: {
        'Content-Security-Policy': 'allow "self"; unsafe-inline; img-src "self"',
    },
    remove: [ 'Etag' ],
    set: {
        'Custom-Header': '43',
    }
},</code>
                            </td>
                    </tr>

                    <tr>
                        <td>hosts</td>
                        <td><p>A single server may support multiple virtual hosts on a shared IP address endpoint. 
                        The client HTTP request includes a <em>Host</em> header that specifies the desired hostname.
                        The supported virtual hosts are configured via the <em>hosts</em> directive which specifies one
                        more more virtual host configurations.</p>

                        <p>Each virtual host may include other directives to customize the configuration and routes for that
                        specific host. Each host may nominate the specific listen endpoints for the host via the
                        <a href="#attach">attach</a> property. Without an attach property, the virtual host will attach
                        to all listening endpoints.</p>

                        <p>Example:</p>
                            <pre class="code">
hosts: [ {
    name: '*embedthis.com',
    attach: '*:80',
}, {
    name: '*appwebserver.org',
    attach: [
        '*:80',
        '*:4443'
    ],
}]
</pre>
                           </td>
                    </tr>                   
                    <tr>
                        <td>indexes</td>
                        <td>Ordered list of index documents to serve for directory level requests. For example:
<code class="inverted">indexes: [
    'index.esp',
    'index.html'
],</code>
                        </td>
                    </tr>
                    <tr>
                        <td>languages</td>
                        <td>Collection of language definitions to customize served content based on preferred language.
                        For example: <code class="inverted">languages: {
    en: {
        path: '/path/to/english'
        prefix: 'en',
        suffix: 'en',
        default: true,
    }
}</code>             Typically, you would choose one of <em>prefix</em>, <em>suffix</em> or <em>path</em></td>
                    </tr>
                    <tr>
                        <td>limits</td>
                        <td>
                        <a name="limits"></a>
                        Resource limits to "<em>sandbox</em>" the server.
                        Note that values may either be numbers or strings using natural language suffixes like 
                        <em>MB</em> or <em>GB</em>. The <em>rxBody</em>, <em>rxForm</em>, <em>txBody</em> and 
                        <em>upload</em> properties may be set to <em>unlimited</em> to disable the limit checking.
                        For example:
<code class="inverted">limits: {
    buffer:             '32KB',
    cache:              '10MB',
    cacheItem:          '200KB',
    chunk:              '64KB',
    clients:            100,
    connections:        50,
    files:              0,
    keepAlive:          200,
    processes:          0,
    rxBody:             '100K',
    rxForm:             '32K',
    rxHeader:           '32K',
    memory:             '200MB',
    requests:           20,
    sessions:           100,
    txBody:             '2GB',
    upload:             '2GB',
    uri:                '8K',
    webSockets:         20,
    webSocketsMessage:  '50K',
    webSocketsPacket:   '50K',
    webSocketsFrame:    '4K',
    workers:            4,
},</code></td>
                    </tr>
                    <tr>
                        <td>methods</td>
                        <td>List of acceptable HTTP methods. For example:
<code class="inverted">
methods: [
    'get',
    'post',
],</code>
                        Can also set "*" for all possible methods. 
                        The default set of methods is: "DELETE, GET, OPTIONS, POST, PUT".
                        </td>
                    </tr>
                    <tr>
                        <td>params</td>
                        <td>List of required parameters before the request will match the current route.
                        For example:
<code class="inverted">
params: [
    {
        name:   'name',
        value:  'john',
        equals: true,
    }
],
</code>
                        </td>
                    </tr>
                    <tr>
                        <td>pattern</td>
                        <td><p>Matching URI regular expression for requests to be served by the current route.
                        The route pattern is an enhanced JavaScript-compatibile regular expression. It is enhanced by 
                        optionally embedding braced tokens "{name}" in the pattern. During request URI matching, 
                        these tokens are extracted and defined in the request params and are available to the request 
                        and to route targets. To use the standard regular expression repeat syntax <em>{}</em>, quote
                        the braces with back quote <em>\</em>.</p>
                        <p>Sub-expressions and token expressions are also available in route targets as numbered 
                        tokens <em>$N</em>. For example:</p>
                        <code class="inverted">pattern: '^/app/(.*)(\.html)$',</code>

                        <p>This will enable the target <em>$1.${request.Language=fr}.$2</em>.</p>
                        <p>Use <em>^</em> to anchor to the start of the URI and $ for the end of the URI.
                        If the pattern does not start with <em>^</em>, the route pattern will have its parent 
                        route prefix prepended to the pattern.</p>
                        </td>
                    </tr>
                    <tr>
                        <td>pipeline</td>
                        <td>Collection defining the request/response pipeline including filters and handlers.
                        The Filters property is an ordered list of filters which modify the incoming and outgoing request data.
                        Each entry specifies the filter name and the matching URI extensions. Use "*" to match all extensions.
                        The handlers hash specifies supported handlers and the matching URI extensions.
                        For example:
<code class="inverted">
pipeline: {
    filters: [{
        name: 'uploadFilter',
        extensions: [ 'txt', '*' ],
    }],
    handlers: {
        fileHandler: [ 'html', 'gif', 'jpg', 'png', 'pdf', 'ico', 'css', 'js', 'txt' ],
        espHandler:  [ '*' ],
    },
},
</code>
                        </td>
                    </tr>
                    <tr>
                        <td>prefix</td>
                        <td>URI prefix to remove from request URIs before passing to the application.</td>
                    </tr>
                    <tr>
                        <td>redirect</td>
                        <td><p>Collection of redirection rules. These include the failing URI, destination URI and
                        redirection status.</p>
<code class="inverted"> redirect: [
    {
        from: '/pressRelease',
        status: 301,
        to: 'https://${request:serverName}/fixedPressRelease.html'
    } 
]</code>
                    <p>Alternatively, a rule may be just the string "https://" in which case all HTTP content 
                    will be redirected over HTTPS.</p></td>
                    </tr>
                    <tr>
                        <td>renameUploads</td>
                        <td>Automatically rename uploaded files to use the client supplied filename after sanitizing.
                            ESP typically does not use this property and rather, an ESP controller or ESP page should
                            validate the client details and copy / rename the uploaded temporary file as required.
                            Recommended to not use this with ESP and only ever use on a private network. Defaults to false.
                            accumulate in the upload directory.</td>
                    </tr>
                    <tr>
                        <td>resources</td>
                        <td><p>Create routes sets for the requested resources. Route sets select 
                        pre-defined route sets. Some of the available sets are: 'esp-server' and 'esp-restful'.
                        Resource groups create RESTful routes for a resource that has multiple 
                        instances. Singletons create RESTful routes for singleton resources.</p>
<code class="inverted">
resources: {
    sets: [ 'esp-restful' ],
    groups: [ 'users', 'administrators' ],
    singletons: [ 'profile' ],
}
</code></td>
                    </tr>
                    <tr>
                        <td>routes</td>
                        <td>Ordered list of routes. This may be a pre-defined route set name or it may be an 
                        array of routes. Examples:
                            <code class="inverted">
routes: 'esp-restful',
routes [ 'esp-restful'],
routes [ {
    pipeline: {
        handlers: 'espHandler'
    }
    /* Any collection of properties */
}
</code>
                           </td>
                    </tr>
                    <tr>
                        <td>scheme</td>
                        <td>Define the required HTTP protocol scheme for all requests. Set to "https" to permit only
                        secure connections. Alternatively use <em>redirect: "https://"</em> to redirect HTTPS traffic over
                        to HTTPS.</td>
                    </tr>
                    <tr>
                        <td><a href="#server">server</a></td>
                        <td>Collection of properties that apply to the whole server and not per-route. The
                        <em>server</em> collection is special in that it is only parsed when ESP is not hosted in
                        a web server such as Appweb. If hosted, it is expected that the web server will define
                        these attributes externally.</td>
                    </tr>
                    <tr>
                        <td>showErrors</td>
                        <td>Controls if application errors should be displayed in the browser.
                            Set to true to display errors in the browser. Defaults to true if the source is compiled in
                            for debug and false if compiled in release mode.</td>
                    </tr>
                    <tr>
                        <td>source</td>
                        <td>Source file for the responding application. Used by ESP controllers.</td>
                    </tr>
                    <tr>
                        <td><a href="#ssl">ssl</a></td>
                        <td>Collection of SSL configuration.</td>
                    </tr>
                    <tr>
                        <td>stealth</td>
                        <td>Respond in stealth mode emitting as little context information as possible.</td>
                    </tr>
                    <tr>
                        <td>stream</td>
                        <td>Define whether the request body data should be buffered or stream. This property should be an array of objects with "mime", "uri" and "stream" properties. For example: <code class="inverted">stream: [
    { 
        mime: 'application/custom-mime', 
        stream: false, 
        uri: '/some-uri' 
    },
],</code></td>
                    <tr>
                        <td>target</td>
                        <td>Routing destination for processing the request.</td>
                    </tr>
                    <tr>
                        <td><a href="#timeouts">timeouts</a></td>
                        <td>Collection of timeouts. The timeout units are in seconds but may also be defined as
                            strings with natural suffixes such as "20secs", "1day" or "unlimited".
                        <pre class="code">timeouts: {
    exit: '5secs',
    parse: '5secs',
    inactivity: '30secs',
    request: 'unlimited',
    session: '30mins',
}</pre>
                    </tr>
                    <tr>
                        <td>trace</td>
                        <td>Trace filtering collection.
                        For example:
<code class="inverted">trace: {
    location: 'stdout',
    level: '2',
    backup: 5,
    anew: true,
    size: '10MB',
    timestamp: '1hr',
    maxContent: 50000,
},</code>
                        <p>The trace properties are:</p>
                        <ul>
                            <li>location &mdash; Filename to trace to. May also be 'stdout', or 'stderr'.</li>
                            <li>level &mdash; Trace level (0-5) with 5 being the most verbose.</li>
                            <li>backup &mdash; Number of trace backups to keep.</li>
                            <li>anew &mdash; Start trace log anew each time the application restarts.</li>
                            <li>size &mdash; Maximum size of the trace log before it will be restarted.</li>
                            <li>timestamp &mdash; Write a timestamp at this frequency.</li>
                            <li>maxContent &mdash; Maximum size of request body content to trace. Defaults to 40K.</li>
                        </ul>
                        </td>
                    </tr>
                    <tr>
                        <td>xsrf</td>
                        <td>Control if an XSRF anti-forgery token should be checked for POST forms.
                            If enabled, server side ESP form pages should use the following to
                            generate a hidden input field that contains the XSRF token. 
                            <code class="inverted">&lt;% inputSecurityToken(); %&gt;</code> 
                            Ajax requests should use the following to add the security token to the Ajax request payload.
                            Both mechanisms will add an XSRF HTTP header named <em>X-XSRF-TOKEN</em> to the response.
                            For example, this code generates the token on the server and utilizes its value in
                            client-side Javascript.
<code class="inverted">
&lt;script&gt;
    var token = &lt;%= securityToken(); %&gt;;
&lt;/script&gt;
</code>
                            <p>Note: restarting the server or creating a new ESP session will invalidate XSRF tokens. In this
                            case, the form will need to be reloaded to generate a new token.</p>
                        </td>
                    </tr>
                </tbody>
            </table>

            <a name="server"></a>
            <h3>Http Server Configuration &mdash; http.server.*</h3>
            <p>The <em>server</em> collection is special in that it is only parsed when ESP is not hosted in
                a web server such as Appweb. If hosted, it is expected that the web server will define
                these attributes externally. All <em>server</em> properties apply to the whole server and are not
                modifiable per-route.</p>

            <table title="server" class="ui table segment">
                <thead>
                    <tr><th>Name</th><th>Description</th></tr>
                </thead>
                <tbody>
                    <tr>
                        <td>account</td>
                        <td>User and group account names. If defined, ESP must be run as super-user to be able to change
                        accounts. For example:
                        <code class="inverted">http: {
server: {
    account: {
        user: 'www-data',
        group: 'www-data',
    },</code></td>
                    </tr>
                    <tr>
                        <td>chroot</td>
                        <td>Path to set as the <em>root</em> directory when running using the <em>chroot</em> API.</td>
                    </tr>
                    <tr>
                        <td>defenses</td>
                        <td>Set of defense rules that can be utilized by <em>monitors</em>. 
                            
                            <code class="inverted">defenses: {
    block: {
        args: {
            status: 406,
            message: 'Client temporarily banned due to monitored limit exceeded',
            remedy: 'ban',
            period: '30mins',
        },
    },
},</code>
                        </td>
                    </tr>
                    <tr>
                        <td>listen</td>
                        <td>List of IP:PORT endpoints on which to listen for requests.
                        To listen on all network interfaces, use "<em>*</em>". To listen using SSL, add https:// as a prefix.
                        For example:
<code class="inverted">listen: [
    '*:4000',
    'https://127.0.0.1:4443',
],</code>
                        </td>
                    </tr>
                    <tr>
                        <td>log</td>
                        <td>Log file configuration.
                        For example:
<code class="inverted">log: {
    location: 'stdout',
    level: '2',
    backup: 5,
    anew: true,
    size: '10MB',
    timestamp: '1hr',
},</code>
                        <ul>
                            <li>location &mdash; Filename to log to. May also be 'stdout', or 'stderr'.</li>
                            <li>level &mdash; Trace level (0-5) with 5 being the most verbose.</li>
                            <li>backup &mdash; Number of log backups to keep.</li>
                            <li>anew &mdash; Start log anew each time the application restarts.</li>
                            <li>size &mdash; Maximum size of the log before it will be restarted.</li>
                            <li>timestamp &mdash; Write a timestamp at this frequency.</li>
                        </ul>
                        </td>
                    </tr>
                    <tr>
                        <td>monitors</td>
                        <td>Set of counters to monitor for unusual activity.
                        For example:
                        <code class="inverted">missing: {
    expression: 'NotFoundErrors &gt; 5',
    period: '10 secs',
    defenses: [ 'block' ],
    enable: true,
},</code> </td>
                    </tr>
                </tbody>
            </table>

            <a name="auth"></a>
            <h3>Authentication Configuration &mdash; http.auth.*</h3>
            <table title="auth" class="ui table segment">
                <thead>
                    <tr><th>Name</th><th>Description</th></tr>
                </thead>
                <tbody>
                    <tr>
                        <td>auto</td>
                        <td>Collection of automatic login related properties. The <em>auto.name</em> property defines an 
                        account name that the application will automatically login. This is useful during development to bypass the
                        login step. The <em>auto.roles</em> property defines the roles for which the user will be 
                        authorized. The <em>url</em> property defines the URI for the login dialog.</td>
                    </tr>
                    <tr>
                        <td>login</td>
                        <td>Login page when using the <em>form</em> authentication scheme. If the user is not logged in, they
                            will be redirected to this page.</td>
                    </tr>
                    <tr>
                        <td>realm</td>
                        <td>Login realm string if using Basic or Digest authentication abilities.</td>
                    </tr>
                    <tr>
                        <td>require</td>
                        <td>The permitted user account names or roles that are required before authorization for this route. For
                        example:
<code class="inverted">require: {
    roles: [ 'administrator'],
    users: [ 'julie' ]
}, </code>
                        If <em>users</em> is defined, then a user must login before using the application. The
                        <em>users</em> property may be set to a list of users, a string with a single 
                        user name or <em>true</em> to imply any authenticated user. Note: it is 
                        application dependent how the required login feature is implemented.</td>
                        </tr>
                        <tr>
                        <td>single</td>
                        <td>Set to true to permit only one simultaneous login. Ideal for some management user
                        interfaces. Note: it is application dependent how the required login feature is implemented.</td>
                    </tr>
                    <tr>
                        <td>roles</td>
                        <td>Definition of roles that users may perform. Each role consists of a set of abilities or roles.
                        For example:
                        <code class="inverted">roles: {
    executive:      ['manage', 'direct'],
    user:           ['view'],
    administrator:  ['view', 'edit'],
},</code></td>
                    </tr>
                    <tr>
                        <td>session</td>
                        <td><p>Configure the user session details. 
                            The <em>cookie</em> property can define a unique prefix to use for the session cookie.
                            The default session cookie prefix is: "-http-session-". If set to 'none', then no cookie is 
                            emitted. The <em>visible</em>property specifies whether the cookie is readable by scripts in the browser.
                            By default, the session cookie is not visible to Javascript. It is desirable to keep the 
                            session cookie invisible to minimize XSS security vulnerabilities.</p>
                            <p>ESP implements this by adding the <em>httpOnly</em> option on the <em>Set-Cookie</em>
                            response header.</p>

                            <p>The <em>persist</em> property defines if the cookie is persisted to disk in the browser.
                            If false, the browser discards the cookie when the browser exits. Otherwise the cookie is
                            retained until the session timeout limit expires.</p>
<code class="inverted">
session: {
    cookie: "-esp-cookie-",
    persist: true,
    visible: true,
},
</code>
                        </td>
                    </tr>
                    <tr>
                        <td>store</td>
                        <td>Authentication store. Set to "app", "config", or "system".</td>
                    </tr>
                    <tr>
                        <td>type</td>
                        <td>Authentication type. Set to "basic", "digest" or "form". No need to define if
                            using the "app" authentication store.</td>
                    </tr>
                    <tr>
                        <td>users</td>
                        <td>Definition of users, their passwords and roles if using the "config" authentication
                            store.  For example:
                        <code class="inverted">users: {
    ralph: {
        password: 'BF1:00128:bWFC5x45BYfuf2GW:w+zzIU0wTZQYaNae0sPecWyry8Z9GrKH',
        roles:    ['user', 'administrator', 'purchase'],
    },
},</code>
                        </td>
                    </tr>
                </tbody>
            </table>

            <a name="cache"></a>
            <h3>Cache Collection &mdash; http.cache.*</h3>
            <p>The cache property contains a list of cache records. For example:</p>
<code class="inverted">cache: [{
    client: '1day',
    extensions: [ 'css', 'html', 'js' ],
}],</code>
            <p>The cache property may also be set to <em>true</em> which is equivalent to defining
            caching on the client side for one day for common static file types.</p>

            <table title="cache" class="ui table segment">
                <thead>
                    <tr><th>Name</th><th>Description</th></tr>
                </thead>
                <tbody>
                    <tr>
                        <td>extensions</td>
                        <td>List of extensions to cache</td>
                    </tr>
                    <tr>
                        <td>client</td>
                        <td>Define the lifespan of content cached in the client's browser. For example: client="1hour</td>
                    </tr>
                    <tr>
                        <td>server</td>
                        <td>Define the lifespan of content cached in the server. For example: server="1hour</td>
                    </tr>
                    <tr>
                        <td>manual</td>
                        <td>If true, then do not transparently cache qualifying response output. Rather, the application
                        must seed the cache manually via httpWriteCached</td>
                    </tr>
                    <tr>
                        <td>methods</td>
                        <td>List of HTTP request methods to cache.</td>
                    </tr>
                    <tr>
                        <td>mime</td>
                        <td>List of request content mime types to cache. For example:
                        <code class="inverted">mime: [ 'image/jpeg', 'image/png' ]</code></td>
                    </tr>
                    <tr>
                        <td>unique</td>
                        <td>Uniquely cache requests using the full URI including the request query and parameters. By default,
                        only the URI without parameters is considered when caching content.</td>
                    </tr>
                    <tr>
                        <td>uris</td>
                        <td>List of qualifying URIs to cache</td>
                    </tr>
                </tbody>
            </table>

            <a name="ssl"></a>
            <h3>SSL Collection &mdash; http.ssl.*</h3>
            <p>The content property describes how web content should be built and processed.
            The SSL directives may be used globally or per-route.</p>
<code class="inverted">ssl {
    authority: {
        file:       'ca.crt',
        directory:  './ca-dir',
    },
    certificate:    'mycert.crt',
    ciphers: [
                    'TLS_RSA_WITH_AES_256_CBC_SHA',
                    'TLS_RSA_WITH_RC4_128_SHA'
    ],
    key:            'mykey.key',
    verify: {
        client:     true,
        issuer:     true,
    },
},</code>
            <table title="ssl" class="ui table segment">
                <thead>
                    <tr><th>Name</th><th>Description</th></tr>
                </thead>
                <tbody>
                    <tr>
                        <td>authority</td>
                        <td>Certificate authority <em>file</em> or <em>directory</em>. Choose one of these two properties
                        to define the CA certificates for verifying clients. Only used if ssl.verify.client or ssl.verify.issuer
                        is true.</td>
                    </tr>
                    <tr>
                        <td>certificate</td>
                        <td>Path to the SSL certificate to use for connections on this route.</td>
                    </tr>
                    <tr>
                        <td>ciphers</td>
                        <td>List of acceptable ciphers to use. These names are dependant on the SSL provider selected
                        The format of this directive varies depending on the SSL protocol stack. 
                        The OpenSSL stack uses its own proprietary 
                        cipher naming. If using OpenSSL, please consult the 
                        <a href="http://www.openssl.org/docs/apps/ciphers.html">OpenSSL</a> documentation for how to format 
                        the ciphers.  Other stack use the standard 
                        <a href="http://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-3">IANA Cipher Suite Registry</a>a names. 
                        </td>
                    </tr>
                    <tr>
                        <td>key</td>
                        <td>Path to the private key file for connections on this route.</td>
                    </tr>
                    <tr>
                        <td>verify</td>
                        <td>Control whether client certificates are required and verified. If 
                        <em>verify.client</em> is true, the client must provide a valid certificate. If 
                        <em>verify.issuer</em> is true, the client's certificate must be verifiable by the
                        specified <em>authority</em> certificate.</td>
                    </tr>
            </table>

            <a name="timeouts"></a>
            <h3>Timeouts Collection &mdash; http.timeouts.*</h3>
            <p>The timeouts property specifies the various request and connection timeouts.
                Timeouts are expressed as strings with natural language suffixes like: "30mins".</p>
            <table title="ssl" class="ui table segment">
                <thead>
                    <tr><th>Name</th><th>Description</th></tr>
                </thead>
                <tbody>
                    <tr>
                        <td>exit</td>
                        <td>Maximum exit delay while waiting for requests to complete.</td>
                    </tr>
                    <tr>
                        <td>parse</td>
                        <td>Maximum time to receive a the request headers. Default 5 seconds.</td>
                    </tr>
                    <tr>
                        <td>inactivity</td>
                        <td>Maximum time a connection will be preserved in the absence of I/O activity. Default 30 seconds.</td>
                    </tr>
                    <tr>
                        <td>refresh</td>
                        <td>Default time to refresh pages with dynamic content.</td>
                    </tr>
                    <tr>
                        <td>request</td>
                        <td>Maximum time for a request to complete. Default infinite.</td>
                    </tr>
                    <tr>
                        <td>session</td>
                        <td>Maximum time to preserve session state storage for a client. Default 5 minutes.</td>
                    </tr>
            </table>
